Immutable folder support in DABs by andrewnester · Pull Request #5254 · databricks/cli

andrewnester · 2026-05-15T09:56:18Z

Changes

Added support for deploying bundles to immutable folders in the workspace

Enabled by using

bundle:
  deployment: 
    immutable_folder: true

Why

Tests

Added an acceptance tests

eng-dev-ecosystem-bot · 2026-05-28T11:17:06Z

Integration test report

Commit: e26f085

Run: 28094333178

	Env	🟨KNOWN	🔄flaky	💚RECOVERED	🙈SKIP	✅pass	🙈skip	Time
🟨	aws linux	7			13	244	1028	5:32
🟨	aws windows	7			13	246	1026	8:02
💚	aws-ucws linux			7	13	334	944	5:29
💚	aws-ucws windows			7	13	336	942	5:40
💚	azure linux			1	15	247	1026	4:43
💚	azure windows			1	15	249	1024	5:13
🔄	azure-ucws linux		2	1	15	337	940	9:00
🔄	azure-ucws windows		2	1	15	339	938	7:27
💚	gcp linux			1	15	246	1028	4:15
💚	gcp windows			1	15	248	1026	4:49

22 interesting tests: 13 SKIP, 7 KNOWN, 2 flaky

	Test Name	aws linux	aws windows	aws-ucws linux	aws-ucws windows	azure linux	azure windows	azure-ucws linux	azure-ucws windows	gcp linux	gcp windows
🟨	TestAccept	🟨K	🟨K	💚R	💚R	💚R	💚R	💚R	💚R	💚R	💚R
🙈	TestAccept/bundle/invariant/no_drift	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/permissions	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🟨	TestAccept/bundle/resources/permissions/jobs/destroy_without_mgmtperms/with_permissions	🟨K	🟨K	💚R	💚R	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🟨	TestAccept/bundle/resources/permissions/jobs/destroy_without_mgmtperms/with_permissions/DATABRICKS_BUNDLE_ENGINE=direct	🟨K	🟨K	💚R	💚R
🟨	TestAccept/bundle/resources/permissions/jobs/destroy_without_mgmtperms/with_permissions/DATABRICKS_BUNDLE_ENGINE=terraform	🟨K	🟨K	💚R	💚R
🟨	TestAccept/bundle/resources/permissions/jobs/destroy_without_mgmtperms/without_permissions	🟨K	🟨K	💚R	💚R	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🟨	TestAccept/bundle/resources/permissions/jobs/destroy_without_mgmtperms/without_permissions/DATABRICKS_BUNDLE_ENGINE=direct	🟨K	🟨K	💚R	💚R
🟨	TestAccept/bundle/resources/permissions/jobs/destroy_without_mgmtperms/without_permissions/DATABRICKS_BUNDLE_ENGINE=terraform	🟨K	🟨K	💚R	💚R
🙈	TestAccept/bundle/resources/postgres_branches/basic	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/postgres_branches/recreate	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/postgres_branches/replace_existing	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/postgres_branches/update_protected	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/postgres_branches/without_branch_id	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/postgres_endpoints/basic	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/postgres_projects/update_display_name	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/synced_database_tables/basic	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/vector_search_endpoints/drift/recreated_same_name	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/bundle/resources/vector_search_indexes/recreate/embedding_dimension	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🙈	TestAccept/ssh/connection	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🔄	TestFetchRepositoryInfoAPI_FromRepo/root	✅p	✅p	✅p	✅p	✅p	✅p	🔄f	🔄f	✅p	✅p
🔄	TestFetchRepositoryInfoAPI_FromRepo/subdir	✅p	✅p	✅p	✅p	✅p	✅p	🔄f	🔄f	✅p	✅p

Top 4 slowest tests (at least 2 minutes):

duration	env	testname
3:24	azure windows	TestAccept
3:17	aws-ucws windows	TestAccept
3:15	azure-ucws windows	TestAccept
3:12	gcp windows	TestAccept

github-actions · 2026-06-01T11:35:34Z

Approval status: pending

`/acceptance/bundle/` - needs approval

30 files changed
Suggested: @denik
Also eligible: @pietern, @janniklasrose, @shreyas-goenka, @lennartkats-db, @anton-107

`/bundle/` - needs approval

28 files changed
Suggested: @denik
Also eligible: @pietern, @janniklasrose, @shreyas-goenka, @lennartkats-db, @anton-107

`/cmd/bundle/` - needs approval

Files: cmd/bundle/run.go, cmd/bundle/utils/process.go
Suggested: @denik
Also eligible: @pietern, @janniklasrose, @shreyas-goenka, @lennartkats-db, @anton-107

`/libs/sync/` - needs approval

Files: libs/sync/sync.go
Suggested: @simonfaltum
Also eligible: @Divyansh-db, @tanmay-db, @renaudhartert-db, @parthban-db, @hectorcast-db, @tejaskochar-db, @mihaimitrea-db, @chrisst, @rauchy

General files (require maintainer)

Files: acceptance/bin/print_requests.py, libs/testserver/handlers.go
Based on git history:

@denik -- recent work in bundle/direct/, bundle/phases/, bundle/config/mutator/

_{Any maintainer (@anton-107, @denik, @pietern, @shreyas-goenka, @simonfaltum, @renaudhartert-db) can approve all areas.

See OWNERS for ownership rules.}

shreyas-goenka

Minor comments - other than the bit where we use metadata.json

shreyas-goenka · 2026-06-02T16:30:01Z

@@ -15,6 +15,9 @@ type Bundle struct {

 type Workspace struct {
 	FilePath string `json:"file_path"`
+	// SnapshotPath is the workspace path of the immutable snapshot uploaded
+	// during deployment. Only populated for bundles with bundle.immutable = true.
+	SnapshotPath string `json:"snapshot_path,omitempty"`


Will the UI use the immutable snapshot path? In that case we'll need to add it to DMS as well.

shreyas-goenka · 2026-06-19T12:13:58Z

+		}
+
+		// The real API uses the workspace user UUID (not email) in the snapshot path,
+		// matching service-principal identities used in cloud acceptance tests.


optional: Should we also use UUIDs here for better fidelity? The benefits are minor if we have cloud coverage. The difference being users have CAN_MANAGE always on their home directory but that's likely not true for /Users/userId?

shreyas-goenka · 2026-06-19T12:27:36Z

            Whether to fail on active runs. If this is set to true a deployment that is running can be interrupted.
+        "immutable_folder":
+          "description": |-
+            Whether to upload bundle files and artifacts as a single immutable snapshot. When true, all files are packaged into a zip and uploaded via the snapshot API, and workspace.file_path and workspace.artifact_path are set to the returned content-addressed path. The validate and plan commands make no mutative API calls when this is enabled.


Snapshots API is internal. We should not refer to this in the docs.

shreyas-goenka · 2026-06-19T12:30:36Z

+func (m *translateResourcePaths) Name() string { return "snapshot.TranslateResourcePaths" }
+
+func (m *translateResourcePaths) Apply(_ context.Context, b *bundle.Bundle) diag.Diagnostics {
+	localPrefix := b.SyncRootPath + "/"


Maybe strings.TrimSuffix("/") as well to account for trailing /? Or is that not possible?

shreyas-goenka · 2026-06-19T12:34:21Z

+
+// SaveState writes the snapshot path to the local deployment state directory
+// so it can be recovered during destroy without reading metadata.json.
+func SaveState() bundle.Mutator {


Consider integrating this with deployment WAL? If we can record the snapshot upload event we can avoid reuploading it on a subsequent deployment since it already exists.

We can't really, can we? The deployment WAL calculated before the execution of deployment as part of plan but we build and upload later in the phase

I assume during deployments we write to WAL so surely we should be able to do that during / after file upload? Otherwise do how do we capture if the plan was partially applied.

I could be misunderstanding the WAL - I'm not familiar with it (will look into it) - I just assumed it records actions as we do them.

Sorry, I misunderstood you and thought you're talking about execution graph and not WAL :) WAL indeed makes sense but it's currently limitted to only creation of resources. I think it might worth expanding it generally to more steps of deploy but this is outside of the scope

pietern · 2026-06-23T06:46:34Z

+}
+
+func (m *overrideImmutableFolder) Apply(ctx context.Context, b *bundle.Bundle) diag.Diagnostics {
+	if env.Get(ctx, "DATABRICKS_IMMUTABLE_FOLDER") == "" {


For later: move to bundle/env to centralize all env vars we use, and infix with _BUNDLE_.

pietern · 2026-06-23T06:53:10Z

 	state.Files = fl

+	// Persist the snapshot path so destroy on a different machine can find it.
+	state.SnapshotPath = b.Config.Workspace.SnapshotPath


This state file is not needed for destroy today because we remove the file path recursively.

Storing a different path means there is proper state to keep track of.

Can this be implemented as a (hidden?) direct engine resource instead? Then we keep track of it next to the other state, benefit from the WAL, can auto-resolve paths on deployment, etc.

Agreed, this might be useful. The only limitation I see it is that this will be only available for direct engine while now it's both.
Also I believe we don't strictly need this in the version revision of the feature and can follow up with this later

pietern · 2026-06-23T06:54:24Z

+	}
+	return s.GetFileList(ctx)
+}
+


We also have a "GetSyncOptions" somewhere. Can we reuse that to get to the file list without duplicating?

Fixed here: 3a0ec41

This can be removed if no longer used.

pietern · 2026-06-24T08:04:26Z

+
+      hint: Packages were unavailable because the network was disabled. When
+      the network is disabled, registry packages may only be read from the
+      cache.


Is this supposed to fail?

pietern · 2026-06-24T08:13:41Z

 		return
 	}

+	if b.Config.Experimental == nil || !b.Config.Experimental.ImmutableFolder {


Collapse into a single var at the top of this function so we don't need to repeat it and two modes are clear.

pietern · 2026-06-24T08:15:46Z

+		// Allows running the full test suite against the immutable folder code path without
+		// modifying any databricks.yml files.
+		mutator.OverrideImmutableFolder(),
+


Is this test only?

Yes, this is only used for test

pietern · 2026-06-24T08:16:45Z

+	}
+	return s.GetFileList(ctx)
+}
+


This can be removed if no longer used.

pietern · 2026-06-24T08:26:28Z

+		})
+	}
+	return acl
+}


Nit: can live in a different file.

Immutable folder support in DABs

b685ec2

andrewnester requested a review from pietern May 15, 2026 09:56

andrewnester temporarily deployed to test-trigger-is May 15, 2026 09:56 — with GitHub Actions Inactive

andrewnester added 2 commits May 28, 2026 11:03

remove unused snapshot path method

a429b26

added an acceptance test

e7c1968

andrewnester temporarily deployed to test-trigger-is May 28, 2026 10:01 — with GitHub Actions Inactive

fix for notebook import

67914d0

andrewnester temporarily deployed to test-trigger-is May 28, 2026 10:19 — with GitHub Actions Inactive

removed unused function

549492a

andrewnester temporarily deployed to test-trigger-is May 28, 2026 10:41 — with GitHub Actions Inactive

andrewnester marked this pull request as ready for review June 1, 2026 11:34

fix schema + unit test

aedfdb0

andrewnester temporarily deployed to test-trigger-is June 1, 2026 11:39 — with GitHub Actions Inactive

andrewnester requested a review from denik June 2, 2026 10:01

shreyas-goenka reviewed Jun 2, 2026

View reviewed changes

andrewnester and others added 2 commits June 9, 2026 12:49

use immutable_folder config

eddec61

Merge branch 'main' into demo-immutable

27a6b02

andrewnester temporarily deployed to test-trigger-is June 9, 2026 10:51 — with GitHub Actions Inactive

remove merge conflict

4a9bcd9

andrewnester temporarily deployed to test-trigger-is June 9, 2026 10:53 — with GitHub Actions Inactive

fix empty artifact path + tests

ebd26ea

andrewnester added 2 commits June 18, 2026 18:56

fix lint

d978559

do not call set permissions on immutable ws root

9a6c898

andrewnester temporarily deployed to test-trigger-is June 18, 2026 17:00 — with GitHub Actions Inactive

shreyas-goenka reviewed Jun 19, 2026

View reviewed changes

addressed feedback

079998b

andrewnester temporarily deployed to test-trigger-is June 22, 2026 08:40 — with GitHub Actions Inactive

andrewnester requested a review from shreyas-goenka June 22, 2026 08:41

pietern reviewed Jun 23, 2026

View reviewed changes

no destroy + acl + fix for empty path

c6b1ff5

andrewnester temporarily deployed to test-trigger-is June 23, 2026 10:11 — with GitHub Actions Inactive

pr feedback

3a0ec41

andrewnester temporarily deployed to test-trigger-is June 23, 2026 10:31 — with GitHub Actions Inactive

andrewnester requested a review from pietern June 23, 2026 11:00

fixed app deploying

b9f67f7

andrewnester temporarily deployed to test-trigger-is June 23, 2026 11:48 — with GitHub Actions Inactive

use snapshot_path veriable prefixes and move to experimetal

01136f5

andrewnester temporarily deployed to test-trigger-is June 23, 2026 15:49 — with GitHub Actions Inactive

pietern reviewed Jun 24, 2026

View reviewed changes

Merge branch 'main' into demo-immutable

6e9aa77

andrewnester temporarily deployed to test-trigger-is June 24, 2026 09:33 — with GitHub Actions Inactive

addressed feedback

e26f085

andrewnester temporarily deployed to test-trigger-is June 24, 2026 11:11 — with GitHub Actions Inactive

Conversation

andrewnester commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Why

Tests

Uh oh!

eng-dev-ecosystem-bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Integration test report

Uh oh!

github-actions Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approval status: pending

/acceptance/bundle/ - needs approval

/bundle/ - needs approval

/cmd/bundle/ - needs approval

/libs/sync/ - needs approval

General files (require maintainer)

Uh oh!

shreyas-goenka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shreyas-goenka Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrewnester commented May 15, 2026 •

edited

Loading

eng-dev-ecosystem-bot commented May 28, 2026 •

edited

Loading

github-actions Bot commented Jun 1, 2026 •

edited

Loading

`/acceptance/bundle/` - needs approval

`/bundle/` - needs approval

`/cmd/bundle/` - needs approval

`/libs/sync/` - needs approval

shreyas-goenka Jun 19, 2026 •

edited

Loading